home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / olrdrs / qwkndt1a.zip / SCRIPT.DOC < prev    next >
Text File  |  1992-11-06  |  7KB  |  198 lines
  1.                      The QWK'n'Dirty Script Language
  2.                            Copyright 1992 by
  3.                            Anthony W. Hursh
  4.  
  5.  
  6.         Many terminal programs have a script language that can
  7. be used to automate the logon process. The QWK'n'Dirty script
  8. language goes beyond that. It lets you automatically upload and
  9. download .REP and .QWK packets without any human intervention,
  10. something that would be difficult (if not impossible) with most
  11. other script languages.
  12.  
  13.         A QWK'n'Dirty script is a text file with a .SCR extension.
  14. To use a script, go into the QWK'n'Dirty dialing menu and choose [E]
  15. to edit the system. When you're asked for the name of the script file,
  16. enter the file name of your script. Do not enter the .SCR extension. This
  17. is automatically added by QWK'n'Dirty. The next time you call that system
  18. QWK'n'Dirty will execute the script.
  19.  
  20.         Several example scripts are included with the QWK'n'Dirty
  21. distribution. After reading this document, you should study them
  22. to gain a further insight into how the script language works.
  23.  
  24.                           SCRIPT COMMANDS
  25.  
  26. A QWK'n'Dirty script command consists of a keyword optionally followed by
  27. character strings or numbers. Keywords can be typed in either lower or
  28. upper case, whichever you prefer. In the following command list,
  29. <string> denotes an arbitrary sequence of characters. [number]
  30. denotes a decimal number. Strings must be enclosed in double quotes,
  31. but do not quote numbers.
  32.  
  33. SEND <string>
  34.  
  35.         This is used to send a character string to the remote system.
  36.         The command:
  37.  
  38.         SEND "FOOBAR"
  39.  
  40.         will cause the word _FOOBAR_ to be sent out the modem.
  41.         The command:
  42.  
  43.         SEND "luser\r"
  44.  
  45.         will send the word _luser_, followed by a carriage return. The
  46.         \r is an escape sequence for carriage return. See "Escape
  47.         Sequences", below, for other available escape sequences.
  48.  
  49.  
  50. EXPECT <expected> <failure> [retries]
  51.  
  52.  
  53.         The EXPECT command waits for the <expected> string until
  54.         it's either received or the timeout period expires (see
  55.         TIMEOUT, below). <failure> and [retries] are optional.
  56.         If the <failure> string is supplied, it is sent in the event
  57.         of a timeout. [retries] is the number of times to check for the
  58.         <expected> string. If [retries] is used, <failure> must also be
  59.         present.
  60.  
  61.         The command:
  62.  
  63.         EXPECT "login:"
  64.  
  65.         will wait for the string _login:_ to be sent from the remote
  66.         system. If it is received before the timeout period has
  67.         expired, the script continues executing. If the timeout
  68.         period *does* expire before getting _login:_, script execution
  69.         will be aborted. In addition, if QWK'n'Dirty is running in Golem
  70.         Mode (unattended), it will attempt to hang up the phone if an
  71.         EXPECT command times out.
  72.  
  73.         The command:
  74.  
  75.         EXPECT "username:" "\r" 5
  76.  
  77.         will wait for the string _username:_ to be sent from the
  78.         remote system. If it is not received within the timeout
  79.         period, QWK'n'Dirty will send a carriage return (the "\r") and
  80.         try  again. QWK'n'Dirty will continue waiting for _username:_
  81.         and sending return for a maximum of [retries] times, 5 times
  82.         in this example. If it doesn't see _username:_ within 5 tries
  83.         the script is aborted. This feature is handy for systems that
  84.         require you to hit return a number of times to "wake up the
  85.         modem" before logging on.
  86.  
  87.         Be warned: the <expected> string *is* case sensitive.
  88.  
  89.         EXPECT "username:"
  90.  
  91.         is *not* the same as
  92.  
  93.         EXPECT "Username:"
  94.  
  95.         Make sure to enter the strings in the same case that the BBS
  96.         uses.
  97.  
  98.  
  99. UPLOAD
  100.  
  101.         This command uploads a .REP packet to the BBS using the
  102.         previously selected protocol.
  103.  
  104.  
  105. DOWNLOAD
  106.  
  107.         This command downloads a .QWK packet from the BBS using
  108.         the previously selected protocol.
  109.  
  110.  
  111. TIMEOUT [seconds]
  112.  
  113.         This command is used to adjust the timeout period for
  114.         the EXPECT command. By default, the timeout period
  115.         is set for 30 seconds. The command:
  116.  
  117.         TIMEOUT 10
  118.  
  119.         will set the timeout period to 10 seconds instead.
  120.         The new setting remains in effect until another
  121.         TIMEOUT command is issued.
  122.  
  123.  
  124. SLEEP [seconds]
  125.  
  126.         This command causes the script to "go to sleep" for the
  127.         specified number of seconds. It's useful for wasting
  128.         time while (e.g.) a program loads on the BBS or the
  129.         QWK packet is being generated. The command:
  130.  
  131.         SLEEP 5
  132.  
  133.         will cause the script to go on hold for 5 seconds.
  134.  
  135.  
  136. REPBEGIN
  137.  
  138.         This command is used to introduce the .REP section. Any
  139.         script commands between REPBEGIN and REPEND will be
  140.         executed only if there is a .REP packet waiting for the
  141.         system.
  142.  
  143.  
  144. REPEND
  145.  
  146.         This command is used to end the .REP section.
  147.  
  148.  
  149. HANGUP
  150.  
  151.         Attempt to hang up the phone.
  152.  
  153.  
  154. PAUSESTR <pause> <unpause>
  155.  
  156.         Sets the "pause string" for the script. Many BBS programs
  157.         send a specific string at the end of a screen of text.
  158.         It's usually something like "--More--", "Press enter to
  159.         continue", "[PAUSE]", or the like. It's hard to predict
  160.         exactly when these pauses will occur because sysops
  161.         have a tendency to change these text screens often.
  162.         With PAUSESTR you can avoid having this mess up your
  163.         scripts. If you set PAUSESTR, any time QWK'n'Dirty detects the
  164.         <pause> string while it's in an EXPECT command it sends
  165.         the <unpause> string. The command:
  166.  
  167.         PAUSESTR "Press ENTER to continue" "\r"
  168.  
  169.         will cause QWK'n'Dirty to send a return every time it sees
  170.         _Press ENTER to continue_. The command:
  171.  
  172.         PAUSESTR "--More--" "n\r"
  173.  
  174.         will cause QWK'n'Dirty to send n followed by return every time
  175.         it sees a _--More--_ prompt. PAUSESTR can be use with any
  176.         sort of repetitive screen pause prompt.
  177.  
  178.  
  179.  
  180.                            ESCAPE SEQUENCES
  181.  
  182. Sometimes you'll need to send or detect a character that is difficult
  183. or impossible to type directly. For these situations, the script
  184. language allows you to use escape sequences. An escape sequence
  185. consists of a backslash character followed by another character.
  186. The following escape sequences are recognized by QWK'n'Dirty:
  187.  
  188.          \r  carriage return (ASCII 13)
  189.          \n  line feed  (ASCII 10)
  190.          \t  tab  (ASCII 9)
  191.          \b  backspace (ASCII 8)
  192.          \c  Control-C (ASCII 3)
  193.          \e  Escape (ASCII 27)
  194.          \x  Control-X (ASCII 24)
  195.          \"  Double quote (ASCII 34)
  196.          \\  Backslash (ASCII 92)
  197.  
  198.